Alias

CscOauth2Token

Description

Obtains an OAuth 2.0 access token.

Request

To obtain the access token attesting to an authorization grant, the client application must send a request like the following to the TRIDENT using TLS. Note that this request is sent directly from the client application to the TRIDENT and does not go through the browser, the same as in Push an OAuth 2.0 authorization request and the opposite to the exchange described in Obtain an OAuth 2.0 Authorization.

POST /trustedx-resources/csc/v2/oauth2/token

Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be /csc/v2/. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is /csc/v2 instead of /trustedx-resources/csc/v2. To determine if this is the case in your situation, check the "oauth2" property of the JSON object provided by the Obtain information on the CSC signature service operation.

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Request Parameters

The parameters of the request (in its body) vary according to the type of OAuth 2.0 flow in which the token is requested:

Parameters in the Case of the Authorization Code Grant Flow
Parameters in the Case of the Client Credentials Grant Flow

Parameters in the Case of the Authorization Code Grant Flow

Name	Type	Usage	Description
`grant_type`	String	Required	Must have the value `authorization_code`.
`code`	String	Required	Code of the authorization for which a token is requested (i.e., the access token). This code must be the code received in the response of the Obtain an OAuth 2.0 authorization operation previously invoked.
`code_verifer`	String	Conditionally required	Value from which was derived the `code_challenge` included in the Obtain an OAuth 2.0 authorization's request that obtained the `code` parameter (or in the associated pushed authorization request). This value must be generated randomly with a high entropy as per RFC 7636. It must be used only if the `code_challenge` was included in the Obtain an OAuth 2.0 authorization request ( or in the associated pushed authorization request) being mandatory in that case.
`client_id`	String	Required	Identifier of the client assigned by TRIDENT to the signature application.
`redirect_uri`	String	Optional	URI where the authorization response was received with the authorization code put in `code`. It must match the `redirect_uri` parameter of the authorization request (see Obtain an OAuth 2.0 authorization). It must be omitted if it is also omitted in the authorization request.

Parameters in the Case of the Client Credentials Grant Flow

Name	Type	Usage	Description
`grant_type`	String	Required	Must have the value `client_credentials`.
`client_id`	String	Required	Identifier of the client assigned by TRIDENT to the signature application.

In Client Credential flows, the scope of the access token requested will always be service implicitly.

Authentication of the Client Application

The application must include an Authorization header with the following structure:

Authorization: Basic {credentials}

Where {credentials} is the result of encoding the client identifier of the application (client_id) and its secret (client_secret) as follows:

base64(url_encode(utf8(client_id)) ':' url_encode(utf8(client_secret)))

The meaning of the above pseudocode is:

Encode client_id in UTF-8. Next, encode the results obtained by applying the URL character escape rules.
Encode client_secret in UTF-8. Next, encode the results obtained by applying the URL character escape rules.
Concatenate both using colons (":") as the separator.
Encode the resulting string in base64 without line breaks.

The rules for escaping characters in URLs are those defined for the application/x-www-form-urlencoded MIME format in the HTML specification, and must be applied to the bytes resulting from encoding the identifier or secret in UTF-8. See the example below.

Note

The HTTP basic authentication scheme defined in RFC 2617 does not specify that the credentials must be encoded in UTF-8 and URL format. The use of these additional encoding rules is part of OAuth 2.0. If a software library or tool that generates the Authorization header as per RFC 2617 is used, remember this, especially when the identifier or secret contains extended symbols or characters.

Authorization

No access token is required.

Response

As a response, the TRIDENT generates a bearer access token and returns it in a JSON structure. The application must later use this token to invoke the API's required functions.

Status-Line

HTTP/1.1 200 OK

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

JSON object containing the access token and the associated information.

{
   "access_token" : {string},
   "token_type" : "Bearer",
   "expires_in" : {number},
   "credentialID": {string}
}

Property	Type	Description
`access_token`	String	Access token generated by the TRIDENT. If the scope of the authorization granted is `service`, a "`Bearer`" token is obtained and must be put as the value of the `Authorization: Bearer` header of the HTTP message with which an operation is subsequently invoked If the scope of the authorization granted is `credential`, a "`SAD`" token is obtained and must be put as the value of the `SAD` parameter in the body of the HTTP message later used to invoke the Generate digital signatures from hashes operation
`token_type`	String	Type of access token: "`Bearer`": the token is proof of authorization with the `service` scope and must be put as the value of the `Authorization: Bearer` header of the HTTP message used to invoke an operation. "`SAD`": the token is proof of authorization with the `credential` scope and must be put as the value of the SAD parameter of the request used to invoke the Generate digital signatures from hashes operation
`expires_in`	Number	Lifetime (in seconds) of the access token. The application must perform the access the token authorizes before the token expires.
`credentialID`	String	The identifier of the credential associated with the signing key whose use was authorized in the corresponding authorization request. This response parameter will be present in case the scope "`credential"` is used in the pushed authorization request along with the `"eu_eidas_qes"` signature qualifier (`signatureQualifier`) . This can then be used to obtain the authorized signing key certificate.

Error Management

If the access token request cannot be successfully processed (because the request is invalid, the authentication of the client application fails, the authorization code is expired, etc.), the TRIDENT returns an HTTP response with the HTTP 400 (Bad Request) status code, the Content-Type: application/json;charset=utf-8 header and a JSON object in the body with the following properties:

error: Error code.
error_description: Additional description of the error. Not required.

Error case	Status Code (HTTP)	error	error_description
The `client_id` of the application requesting the access token was not provided.	400 Bad Request	`invalid_request`	`noCredentials`
The `client_secret` of the application requesting the access token was not provided.	400 Bad Request	`invalid_request`	`invalidCredentials`
The `grant_type` parameter was not provided.	400 Bad Request	`invalid_request`	`unsupported_grant_type`
The value of the `grant_type` parameter is invalid (i.e., it is neither `authorization_code` nor `client_credentials`)	400 Bad Request	`invalid_request`	`unsupported_grant_type`
The `code` parameter was not provided	400 Bad Request	`invalid_request`	`missingAuthzCode`
The `client_id` provided is invalid.	400 Bad Request	`invalid_request`	`unregisteredClient`
The `client_secret` provided is invalid.	400 Bad Request	`invalid_request`	`invalidCredentials`
The r`edirect_uri` parameter does not match that specified in the authorization request.	400 Bad Request	`invalid_request`	`redirectUriMismatch`
The authorization code is invalid (e.g., it has expired).	400 Bad Request	`invalid_request`	`invalidOrExpiredCode`

Examples

Obtaining an Access Token in an Authorization Code Grant Flow

Request

The signature application (client_id = signatureapp, client_secret = 12345678) sends the following request to the TRIDENT:

POST /trustedx-resources/csc/v2/oauth2/token HTTP/1.1
Host: rse.corporation.com
Authorization: Basic c2lnbmF0dXJlYXBwOjEyMzQ1Njc4
Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code&
code=FhkXf9P269L8g&
code_verifer=F7RZvUwaOgyGpv3y0ar27EsxLnhBnUAXM4IjCvHcxXo&
client_id=signatureapp&
redirect_uri=https%3A%2F%2Fsignatureapp.corporation.com%2Foauth%2Fback

Response

TRIDENT responds to the application, providing it with an access token that has a lifetime of 1 minute.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "access_token": "3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5H3XlFQZ3ndFhkXf9P2",
    "token_type": "Bearer",
    "expires_in": 60
}

Obtaining an Access Token in a Client Credentials Grant Flow

Request

The signature application (client_id = signatureapp, client_secret = 12345678) sends the following request to TRIDENT:

POST /trustedx-resources/csc/v2/oauth2/token HTTP/1.1
Host: rse.corporation.com
Authorization: Basic c2lnbmF0dXJlYXBwOjEyMzQ1Njc4
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&
client_id=signatureapp

Response

TRIDENT responds to the application, providing it with a bearer access token that has a lifetime of 1 hour.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "access_token": "4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA",
    "token_type": "Bearer",
    "expires_in": 3600
}